ExecuteWatchdog (Apache Ant API)

org.apache.tools.ant.taskdefs

## Class ExecuteWatchdog

- java.lang.Object
- - org.apache.tools.ant.taskdefs.ExecuteWatchdog

- All Implemented Interfaces:
    TimeoutObserver

      public class ExecuteWatchdog
      extends java.lang.Object
      implements TimeoutObserver

  Destroys a process running for too long. For example:

       ExecuteWatchdog watchdog = new ExecuteWatchdog(30000);
       Execute exec = new Execute(myloghandler, watchdog);
       exec.setCommandLine(mycmdline);
       int exitvalue = exec.execute();
       if (Execute.isFailure(exitvalue) && watchdog.killedProcess()) {
                    // it was killed on purpose by the watchdog
       }

  Since:
    Ant 1.2
  See Also:
    `Execute`, `Watchdog`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExecuteWatchdog(int timeout)` Deprecated. since 1.5.x. Use constructor with a long type instead. (1.4.x compatibility)
    `ExecuteWatchdog(long timeout)` Creates a new watchdog with a given timeout.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkException()` This method will rethrow the exception that was possibly caught during the run of the process.
    `protected void` | `cleanUp()` reset the monitor flag and the process.
    `boolean` | `isWatching()` Indicates whether or not the watchdog is still monitoring the process.
    `boolean` | `killedProcess()` Indicates whether the last process run was killed on timeout or not.
    `void` | `start(java.lang.Process process)` Watches the given process and terminates it, if it runs for too long.
    `void` | `stop()` Stops the watcher.
    `void` | `timeoutOccured(Watchdog w)` Called after watchdog has finished.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ExecuteWatchdog

          public ExecuteWatchdog(long timeout)

      Creates a new watchdog with a given timeout.
      Parameters:
        `timeout` - the timeout for the process in milliseconds. It must be greater than 0.

    - #### ExecuteWatchdog

          public ExecuteWatchdog(int timeout)

      Deprecated. since 1.5.x. Use constructor with a long type instead. (1.4.x compatibility)
      Parameters:
        `timeout` - the timeout value to use in milliseconds.
      See Also:
        `ExecuteWatchdog(long)`

  - ### Method Detail

    - #### start

          public void start(java.lang.Process process)

      Watches the given process and terminates it, if it runs for too long. All information from the previous run are reset.
      Parameters:
        `process` - the process to monitor. It cannot be `null`
      Throws:
        `java.lang.IllegalStateException` - if a process is still being monitored.

    - #### stop

          public void stop()

      Stops the watcher. It will notify all threads possibly waiting on this object.

    - #### timeoutOccured

          public void timeoutOccured(Watchdog w)

      Called after watchdog has finished. This can be called in the watchdog thread
      Specified by:
        `timeoutOccured` in interface `TimeoutObserver`
      Parameters:
        `w` - the watchdog

    - #### cleanUp

          protected void cleanUp()

      reset the monitor flag and the process.

    - #### checkException

          public void checkException()
                              throws BuildException

      This method will rethrow the exception that was possibly caught during the run of the process. It will only remains valid once the process has been terminated either by 'error', timeout or manual intervention. Information will be discarded once a new process is ran.
      Throws:
        `BuildException` - a wrapped exception over the one that was silently swallowed and stored during the process run.

    - #### isWatching

          public boolean isWatching()

      Indicates whether or not the watchdog is still monitoring the process.
      Returns:
        `true` if the process is still running, otherwise `false`.

    - #### killedProcess

          public boolean killedProcess()

      Indicates whether the last process run was killed on timeout or not.
      Returns:
        `true` if the process was killed otherwise `false`.